.TH std::allocator_traits::allocate_at_least 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::allocator_traits::allocate_at_least \- std::allocator_traits::allocate_at_least

.SH Synopsis
   [[nodiscard]] static constexpr std::allocation_result<pointer,
   size_type>                                                             (since C++23)
       allocate_at_least( Alloc& a, size_type n );

   allocate_at_least calls a.allocate_at_least(n) and returns its result if the call is
   well-formed, otherwise, it is equivalent to return {a.allocate(n), n};.

   allocator_at_least tries to allocate a storage for at least n value_type objects,
   and provides a fallback mechanism that allocates a storage for exact n objects.

.SH Parameters

   a - an allocator used for allocating storage
   n - the lower bound of number of objects to allocate storage for

.SH Return value

   a.allocate_at_least(n) if it is well-formed.

   Otherwise, std::allocation_result<pointer, size_type>{a.allocate(n), n}.

.SH Exceptions

   Throws what and when the selected allocation function throws.

.SH Notes

   The allocate_at_least member function of Allocator types are mainly provided for
   contiguous containers, e.g. std::vector and std::basic_string, in order to reduce
   reallocation by making their capacity match the actually allocated size when
   possible. Because allocate_at_least provides a fallback mechanism, it can be
   directly used where appropriate.

   Given an allocator object a of type Alloc, let result denote the value returned from
   std::allocator_traits<Alloc>::allocate_at_least(a, n), the storage should be
   deallocated by a.deallocate(result.ptr, m) (typically called via
   std::allocator_traits<Alloc>::deallocate(a, result.ptr, m)) in order to avoid memory
   leak.

   The argument m used in deallocation must be not less than n and not greater than
   result.count, otherwise, the behavior is undefined. Note that n is always equal to
   result.count if the allocator does not provide allocate_at_least, which means that m
   is required to be equal to n.

       Feature-test macro       Value    Std          Feature
   __cpp_lib_allocate_at_least 202302L (C++23) allocate_at_least etc.

.SH Example

    This section is incomplete
    Reason: no example

.SH See also

   allocate_at_least allocates uninitialized storage at least as large as requested
   (C++23)           size
                     \fI(public member function of std::allocator<T>)\fP

.SH Category:
     * Todo no example
